home *** CD-ROM | disk | FTP | other *** search
/ Aminet 8 / Aminet 8 (1995)(GTI - Schatztruhe)[!][Oct 1995].iso / Aminet / comm / tcp / IPDial1_7.readme < prev    next >
Text File  |  1995-09-20  |  14KB  |  430 lines
  1. Short:    SLIP dialer; stdin/out terminal program
  2. Author:   wiedmann@neckar-alb.de
  3. Uploader: wiedmann@neckar-alb.de
  4. Type:     comm/tcp
  5.  
  6.  
  7. IPDial - serial device communication program
  8. ============================================
  9.  
  10.  
  11. IPDial is designed especially for creating a SLIP connection via the
  12. modem to a remote host: It can dial the remote hosts number, login
  13. into the host and initilize a SLIP connection. Configuring IPDial
  14. is rather easy, as it reads its command from a textfile.
  15.  
  16.  
  17.  
  18. 1.) Disclaimer: Copyrights, (No) Warranty
  19. -----------------------------------------
  20.  
  21. This program is Copyright (C) 1994
  22.  
  23.     Jochen Wiedmann
  24.     Am Eisteich 9
  25.     72555 Metzingen
  26.     Germany
  27.  
  28.     Phone: (0049) +7123 / 14881
  29.     Mail: wiedmann@neckar-alb.de
  30.  
  31.  
  32. Permission is granted to make and distribute either verbatim and modified
  33. copies of this documentation and the program IPDial provided the copyright
  34. notice and this permission notice are preserved on all copies and the "GNU
  35. General Public License" (in the file COPYING) is distributed as well.
  36.  
  37. The author gives ABSOLUTELY NO warranty that the program described in this
  38. documentation and the results produced by them are correct. The author
  39. cannot be held responsible for ANY damage resulting from the use of this
  40. software.
  41.  
  42.  
  43. 2.) Installation
  44. ----------------
  45.  
  46. Rather simple. Just copy the program to a place in your path and edit
  47. the two files "login.script" and "hangup.script". (See Script file
  48. syntax below for details.)
  49.  
  50. You might want to enter the line
  51.  
  52.     IPDial login.script
  53.  
  54. at the beginning of AmiTCP's startnet script. Thus you get a SLIP
  55. connection by simply typing startnet.
  56.  
  57. Similar you could add the line
  58.  
  59.     IPDial hangup.script
  60.  
  61. at the bottom of the stopnet script.
  62.  
  63.  
  64. 3.) Invocation
  65. --------------
  66.  
  67. IPDial is started like this:
  68.  
  69.     IPDial SCRIPT,ECHO/S,VERBOSE/S,TERMINAL/S,DEVICE/K,PROTOCOL/K,
  70.        UNIT/K/N,BAUD/K/N,RAW/S
  71.  
  72. What IPDial does, depends on the TERMINAL switch: If this is active,
  73. the arguments DEVICE, UNIT, BAUD and PROTOCOL are used to open the
  74. serial.device. Once it is opened, the program acts as a very simple
  75. terminal program. See the "terminal" command for an explanation of
  76. the RAW argument.
  77.  
  78. If TERMINAL is omitted, the given SCRIPT is read and the commands
  79. of the script are executed line by line. (See below) The argument
  80. ECHO instructs IPDial to print the modems replies to stdout, while
  81. VERBOSE is used to show what the program's doing.
  82.  
  83.  
  84. 4.) Script file syntax
  85. ----------------------
  86.  
  87. - Any line of the script file may contain only one command. In
  88.   general command arguments are parsed with ReadArgs(), thus they
  89.   may look like CLI command line arguments: The characters "" may
  90.   surround a string which contains blanks.
  91.  
  92.   Note, that ReadArgs() treats the character '*' as an escape
  93.   sequence: Thus you have to write
  94.  
  95.     ECHO "**"
  96.  
  97.   if you want to print a single '*'.
  98.  
  99. - Empty lines or lines beginning with a semicolon are assumed to
  100.   be comments and thus ignored.
  101.  
  102. - Lines may begin with a label, an alphanumeric word followed by
  103.   a colon. Labels are ignored, except that they may be used as
  104.   destinations for "goto" instructions. (Anyone said BASIC? Yes,
  105.   it is. :-) Labels are case-sensitive.
  106.  
  107. - This is the list of possible commands:
  108.  
  109.     DEVICE NAME/A,PROTOCOL,UNIT/K/N
  110.     Opens the given device NAME with unit UNIT (Default 0).
  111.     This must be compatible to the serial.device. PROTOCOL
  112.     may be one of XONXOFF, RTSCTS, 7WIRE (Synonym for RTSCTS)
  113.     or NONE. Note that explicitly requesting a protocol
  114.     overwrites the defaults set by the Derial preferences
  115.     program.
  116.  
  117.     The DEVICE command should in general be the first command
  118.     of each script.
  119.  
  120.     SET BAUD/N/K,DATABITS/N/K,STOPBITS/N/K,BUFSIZE/N/K,PARITY/K
  121.     This command is used to modify the serial.device parameters.
  122.     Note, that these overwrite the Serial preferences. Possible
  123.     parameters are:
  124.         BAUD        baud rate
  125.         DATABITS    number of databits
  126.         STOPBITS    number of stopbits
  127.         BUFSIZE     read buffer size
  128.         PARITY      one of ODD, EVEN or NONE
  129.  
  130.     SHOWPARMS
  131.     Writes the current serial.device settings to stdout.
  132.  
  133.     ECHO ARGS/M
  134.     This will write the given ARGS to stdout. Note, that these
  135.     strings may contain patterns like \r (Carriage Return),
  136.     \n (Line Feed), \\ (Backslash :-) or \037 (octal digits,
  137.     representing the character ASCII 31.) The arguments are
  138.     separated by blanks, when they are printed.
  139.  
  140.     Sequences like $VAR or ${VAR} will be replaced with the
  141.     value of the environment variable VAR. (Empty string, if
  142.     VAR doesn't exist.) Use $$ to get the $ character itself.
  143.     Note, that $VAR will only work, if the name VAR consists
  144.     of alphanumeric characters only and the name is separated
  145.     with a non-alphanumeric character from the following. For
  146.     example, $VAR+NAME means $VAR and not $VAR+NAME. On the
  147.     other hand $VARNAME means $VARNAME and not $VAR. (Obvious
  148.     reason. :-)
  149.  
  150.     Note that ECHO does not write any Line Feeds or Carriage
  151.     Returns unless you explicitly request it with the respective
  152.     patterns.
  153.  
  154.     SEND ARGS/M
  155.     This command sends the given strings to the serial.device
  156.     using DoIO(). These strings may contain the same patterns
  157.     as described with the ECHO command. Unlike ECHO the arguments
  158.     aren't separeted by blanks.
  159.  
  160.     See ECHO for a description of patterns that may be inserted
  161.     into SEND arguments.
  162.  
  163.     DELAY SECS/A
  164.     Delays the given number of seconds. The value may contain a
  165.     fraction of seconds which is rounded to ticks: 0.5 means
  166.     25 ticks.
  167.  
  168.     WAIT TIMEOUT/K/N/A,ARGS/M
  169.     This command waits until either one of the given strings
  170.     is read from the serial.device or the number of seconds
  171.     given by TIMEOUT has gone.
  172.  
  173.     A variable called STATUS indicates what happened: It contains
  174.     either -1 for timeout or the number of the string that was
  175.     read, beginning with 0. This variable may be used by the
  176.     ON statement.
  177.  
  178.     WAIT arguments are parsed like ECHO arguments. (See above.)
  179.  
  180.     SCAN FORMAT/A,GLOBAL/S,SAVE/S
  181.     Used to scan the buffer read by the last "WAIT" command for
  182.     certain words. These may be used set environment variables.
  183.     The format string may contain the following patterns:
  184.  
  185.         %{WORD%} Ignores any characters until WORD is found in
  186.              the buffer. Use %% to insert the '%' character
  187.              into WORD.
  188.         ' '      Ignores any number (including 0) and kind (blank,
  189.              tab, line feed, carriage return, form feed) of
  190.              white space characters.
  191.         %[VAR%]%(SUFFIX%)
  192.              Reads the next word from the buffer until
  193.              the first white space character and stores it into
  194.              the environment variable VAR.
  195.              The optional SUFFIX is a sequence of characters
  196.              to be removed from the end of the word.
  197.         Any other characters in the format string are simply
  198.         ignored.
  199.  
  200.     Usually environment variables are local (for IPDial and child
  201.     processes only). Use the GLOBAL and SAVE keywords to store
  202.     them in ENV: and ENVARC:, respectively. Note, that SAVE
  203.     implies GLOBAL.
  204.  
  205.     Note, that you can use the SCAN command more than once on the
  206.     same buffer.
  207.  
  208.     Example:
  209.         SCAN "%{Your IP address is%} %[IPADDRESS]%%(.%)"
  210.  
  211.         Scans the buffer for a sentence like
  212.  
  213.         Your IP address is 145.2.1.34.
  214.  
  215.         and stores the value 145.2.1.34 into the variable
  216.         IPADDRESS. Note, that the character '.' is removed.
  217.  
  218.     The SCAN command stores the number of created environment
  219.     variables in the STATUS variable, which can later be used
  220.     by the ON command. Note, that the value -1 is never stored
  221.     in the STATUS variable, you have to use a dummy label in the
  222.     ON command.
  223.  
  224.     ON STATUS GOTO LABELS/M
  225.     There's currently only one version of the ON command.
  226.     An ON command must follow a WAIT or SCAN command. ON reads
  227.     the value of the STATUS variable and jumps to the first
  228.     label, if STATUS is -1, to the second label, if STATUS is 0
  229.     and so on. A typical use of WAIT/ON looks like this:
  230.  
  231.         WAIT TIMEOUT=10 "Login:" "Busy"
  232.         ON STATUS GOTO TimeOut Login Busy
  233.  
  234.         TimeOut:
  235.         ECHO "Timeout happened, aborting.\n"
  236.         EXIT 10
  237.  
  238.         Busy:
  239.         ECHO "Remote busy, delaying...\n"
  240.         DELAY 25
  241.         ECHO "Trying again.\n"
  242.         GOTO DialAgain
  243.  
  244.         Login:
  245.         ;   Execute the login procedure
  246.  
  247.     You do not need to supply a label for any wait string:
  248.     This will suppress jumping and instead continue on
  249.     the next line.
  250.  
  251.     GOTO LABEL/A
  252.     Jumps to the given label
  253.  
  254.     TERMINAL NOECHO/S,RAW/S,EOF
  255.     Enters terminal mode: What you enter at the keyboard will
  256.     be sent to the serial.device and likewise the program will
  257.     display any input from the serial.device to you. The
  258.     TERMINAL command will be finished, if you enter EOF
  259.     (Ctrl-\).
  260.  
  261.     The NOECHO and EOF options can be used to enter a password,
  262.     if you don't like to include it into your login file: NOECHO
  263.     makes your input invisible and the EOF string terminates
  264.     terminal mode as soon, as you type in the first character
  265.     of the string. Thus you can do something like
  266.  
  267.         WAIT TIMEOUT=10 "Password:"
  268.         ON STATUS GOTO TimeOut Password
  269.  
  270.         Password:
  271.         ECHO "Enter login password: "
  272.         TERMINAL EOF="\n" NOECHO
  273.  
  274.     Usually you can send only complete lines to the modem,
  275.     especially this means that you have all editing capabilities
  276.     of the shell available. This is not the case in RAW mode:
  277.     Every character you type will be sent immediately to the
  278.     modem without any buffering or conversions.
  279.  
  280.     Notes:
  281.  
  282.         - You probably must put your modem into NOECHO mode too,
  283.           if you use the "terminal" command for entering a password.
  284.         - NOECHO mode implies RAW mode
  285.  
  286.     SYSTEM ARGS/M
  287.     Executes the command given by ARGS. The arguments will be
  288.     parsed like ECHO and SEND arguments (you may insert
  289.     \ and $ patterns) and separated by blanks. The resulting
  290.     string will be executed. For example
  291.  
  292.         SYSTEM "Echo" "Hello!"
  293.  
  294.     will execute the command "Echo Hello!" and not "EchoHello!".
  295.  
  296.     EXIT RESULT
  297.     Terminates the program, returns the given RESULT. (Defaults
  298.     to 0.)
  299.  
  300.     SETVAR NAME/A,VALUE/A,LOCALONLY/S,GLOBAL/S,SAVE/S
  301.     Sets environment variable NAME to VALUE. If you set the
  302.     GLOBAL switch, your variable will be set in ENV: and not
  303.     in the programs local environment. The SAVE switch forces
  304.     copying to ENVARC:.
  305.  
  306.     Note, that SAVE implies GLOBAL.
  307.  
  308.   Commands are case-insensitive.
  309.  
  310. See the scripts Login.IPDial and Hangup.IPDial as examples.
  311.  
  312.  
  313. 5.) How to create a script file?
  314. --------------------------------
  315.  
  316. Enter the terminal mode. You should now be able to type commands like
  317.  
  318.     ATZ<return>
  319.  
  320. If all goes well, the modem should reply
  321.  
  322.     ATZ
  323.     OK
  324.  
  325. provided, that it is in echo mode. Now try to dial into your remote
  326. host with something like
  327.  
  328.     ATDP07071927920<return>
  329.  
  330. If the remote host's phone line isn't busy, you should eventually
  331. see the remote's login message. This message should explain what
  332. to do. Try it and log out. Now have a look at Login.IPDial, in
  333. general you should understand how to edit it.
  334.  
  335.  
  336. 6.) Recommended Usage
  337. ---------------------
  338.  
  339. Each time you reconfigure AmiTCP, it will destroy your startnet
  340. script. Thus it is not a good idea to modify the startnet script.
  341. Instead create a scriptfile, say "neton", which could look as
  342. follows:
  343.  
  344.     .key ECHO/S,VERBOSE/S
  345.  
  346.     IPDial Work:lib/Login.script <ECHO> <VERBOSE>
  347.     If NOT WARN
  348.     startnet
  349.     EndIf
  350.  
  351. Likewise, create a script "netoff" like this
  352.  
  353.     stopnet
  354.     IPDial Work:lib/Hangup.IPDial
  355.  
  356. And, from now on, use "neton" and "netoff" instead of "startnet"
  357. and "stopnet".
  358.  
  359.  
  360. 7.) History
  361. -----------
  362.  
  363. I never expected IPDial to become a little bit popular. However,
  364. the number of questions and/or enhancement requests forced
  365. new versions: This is 1.6 now. Time for a history, as people
  366. might like to know what's different.
  367.  
  368. V 1.1   23.11.94        Initial version
  369.  
  370. V 1.2   27.02.95        Added terminal mode
  371.             Now using ReadArgs() for command line parsing.
  372.  
  373. V 1.3   09.03.95        Added environment variable aupport to "send"
  374.             command. Added unit support.
  375.  
  376.             Suggested by Quarvon (Jürgen Lang)
  377.  
  378. V 1.4   21.04.95        Added "system" command.
  379.  
  380.             Suggested by Gutgolf (Michael Bauer)
  381.  
  382.             Added environment variable support to "echo"
  383.             command. Terminal mode now converts
  384.             LF to CR/LF, so that modem
  385.             recognizes commands.
  386.             (Let's hope, that will still
  387.             work for entering passwords. :-(
  388.  
  389. V 1.5   30.04.95        Added "scan" command.
  390.  
  391. V 1.6   26.06.95        "delay" command supporting ticks; ParseString()
  392.             supporting octal characters; "wait" command using
  393.             ParseString()
  394.  
  395.             Suggested by Will Bow.
  396.  
  397.             Fixed bug in SerialSend():
  398.             *.io_Device = *.io_Unit
  399.  
  400. V 1.7   21.07.95        Added NOECHO, RAW and EOF options to "terminal"
  401.             command.
  402.  
  403.             Suggested by Klaus Heinz
  404.  
  405.             Added BAUD option to command line.
  406.  
  407.             Added "setvar" command.
  408.  
  409.  
  410. ============================= Archive contents =============================
  411.  
  412. Original  Packed Ratio    Date     Time    Name
  413. -------- ------- ----- --------- --------  -------------
  414.     5188    2023 61.0% 21-Jul-95 17:19:34 +Buffer.c
  415.    17982    6993 61.1% 26-Mar-95 20:18:16 +COPYING
  416.     4474    1674 62.5% 21-Jul-95 17:19:02 +DeviceIO.c
  417.     3891    1271 67.3% 26-Jun-95 19:41:16 +DMakefile
  418.     1818     767 57.8% 21-Apr-95 15:38:44 +Hangup.IPDial
  419.    27760   15536 44.0% 22-Jul-95 11:53:16 +IPDial
  420.    23001    6557 71.4% 22-Jul-95 11:52:28 +IPDial.c
  421.     3079    1188 61.4% 21-Jul-95 17:18:42 +IPDial.h
  422.    12647    5421 57.1% 22-Jul-95 11:49:58 +IPDial.readme
  423.     4223    1480 64.9% 01-May-95 20:32:50 +Login.IPDial
  424.    15050    4304 71.4% 21-Jul-95 17:20:24 +Serial.c
  425.     2082    1083 47.9% 22-Jul-95 11:50:40 +setvar.c
  426.     2102    1031 50.9% 21-Jul-95 17:19:54 +StrReadArgs.c
  427.     4544    1926 57.6% 21-Jul-95 17:19:20 +vsscanf.c
  428. -------- ------- ----- --------- --------
  429.   127841   51254 59.9% 01-Aug-95 22:20:52   14 files
  430.